home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr12 / ncal10.zip / NCAL.DOC < prev    next >
Text File  |  1995-03-23  |  6KB  |  138 lines
  1. NCAL Version 1.0, written by Christopher M. Sokol.
  2. Copyright (c) 1995 Christopher M. Sokol.
  3. All Rights Reserved.
  4.  
  5. NCAL is a calendar program similar to the UNIX cal command.  It is more 
  6. powerful than cal in a number of ways, and I left out the "display the entire
  7. year" option.
  8.  
  9. While browsing a local board, I came across a cal implementation which added
  10. a bunch of functionality.  I had been looking for a way to stop missing
  11. birthdays, so I grabbed it.  This program was pretty good, but I didn't like
  12. a number of things about it.  Source code was included, but upon brief 
  13. examination, I decided that it was too ugly to touch.  So I sat down and wrote
  14. the program that I really wanted.  This is it.
  15.  
  16. NCAL will display events which can be assigned in a fairly flexible manner.
  17. The calendar is displayed in color by default, and ANSI.SYS is not required.
  18. Color display is compatible with NNANSI.SYS, or other text mode accelerators
  19. which change the location of video memory when scrolling.  ANSI.SYS output 
  20. is supported.
  21.  
  22. I really wrote this program for the fun of it.  If you encounter any bugs,
  23. or you think a particular feature would be cool, or you have some good reason
  24. why I should give you the source code, send email to chris@infosafe.com.
  25.  
  26. Usage:
  27.  
  28. NCAL [options] [month [year]]
  29.  
  30. The following options are available:
  31.     -a    Causes NCAL to control display attributes with ANSI sequences,
  32.         rather than writing directly to video memory.
  33.     -f    Only displays events occuring today or in the future, events
  34.         which occured prior to today are not displayed.
  35.     -iFILE    Causes FILE to be read.  The files which NCAL reads define
  36.         events and colors.
  37.     -t    Causes NCAL to output only text; display attributes are not 
  38.         used.  This switch is turned on if NCAL's output is redirected
  39.         or piped.  Specifying -a, however, will cause display 
  40.         attributes to be used, and output as ANSI sequences.
  41.  
  42. month can be specified as a number, a three letter month abbreviation, or
  43. the full month name.
  44.  
  45. The argument @filename in the command line will expand to the contents of the
  46. named file.
  47.  
  48. The files which NCAL reads are divided into three sections: [events], [colors],
  49. and [monocolors].  In addition, a section independant include directive is
  50. defined.
  51.  
  52. Comments can be placed anywhere (except in quoted strings) by preceding them
  53. with a semi-colon.
  54.  
  55. The directive
  56. include file_name
  57. will cause file_name to be added to the list of files which NCAL will read.
  58.  
  59. The [events] section defines text to be printed, and when it should be 
  60. printed.  When NCAL is run, it will display all events which affect the 
  61. displayed month, and the month after that.  Each event in the section defines 
  62. a filter which control whether or not the event should occur.
  63.  
  64. Each event takes one line, with 6 fields.  These fields are as follows:
  65. MONTH DATE YEAR WEEK DAY TEXT
  66. The first 5 fields are integers, and the last one is a quoted string.  NCAL 
  67. loads the entire event list, and then for tests each day in the printable 
  68. range against each event.  The filtering process happens like this:
  69.  
  70. The YEAR field is examined.  If it is -1, this comparison completes 
  71. successfully.  Otherwise, if the YEAR field value is not equal to the 
  72. year being tested, the event is discarded.
  73.  
  74. The MONTH field is examined.  This comparison is the same as the YEAR 
  75. comparison: if it is not -1, and it is not equal to the month being tested,
  76. the event is discarded.
  77.  
  78. If the DATE field is -1, then testing continues with WEEK and DAY, as 
  79. described below.  Otherwise, if the date being tested is equal to the DATE
  80. field, the event occurs on the tested date.
  81.  
  82. The WEEK and DAY fields are used together.  These fields are only tested
  83. when the DATE field is -1.  The DAY field specifies a day of the week, with
  84. 1 to 7 corresponding to Sunday to Saturday.  The WEEK field specified which
  85. day of the month.  For example, WEEK = 2 and DAY = 4 would specify an event
  86. which would occur on the second Wednesday of the month.  -1 is a wild value
  87. with both of these fields: WEEK = -1 and DAY = 2 means every Monday, whereas
  88. WEEK = 3 and DAY = -1 would refer to the range of dates from the 15th to the
  89. 21st.  WEEK = -1 and DAY = -1 defines a daily event, which produces too much
  90. data to be useful.
  91.  
  92. When the TEXT field of the event is printed, it is examined for the construct
  93. {YEAR}, where YEAR is an integer.  If this is found, it will be replaced with
  94. the number (DISPLAYED_YEAR - YEAR), with the appropriate numerical suffix 
  95. added.  Thus, {1969} would display as "26th" in the year 1995.
  96.  
  97. The [colors] section defines color mode display attributes.  Each line in
  98. this section should have the form:
  99. color_name = color_description
  100.  
  101. color_name vlues:
  102.  dates        This is the color of the numbers on the calendar (except for
  103.         today)
  104.  dosbkgnd    This is the normal DOS background color.  This is only used
  105.         in ANSI mode before printing line feeds and before NCAL exits.
  106.  evothermonth    This is the color of the event list for months other than the
  107.         current one.
  108.  evthismonth    This is the color of the event list for events which are 
  109.         occuring this month.
  110.  evtoday    This is the color of events which are occuring today.
  111.  evtodaystar    This is the color of the '***' which marks events occuring
  112.         today.
  113.  header        This is the color of the " Su Mo Tu We Th Fr Sa " at the top
  114.         of the calendar display.
  115.  monthname    This is the color of the month and year line at the top of the
  116.         calendar display.
  117.  today        This is the color of the date in the calendar display for 
  118.         today.
  119.  
  120. color_description is an english description of the color to use.  It has the
  121. following form:
  122. BRIGHT BLINKING WHITE ON BLUE
  123. Bright and blinking are optional attributes.  The following colors are 
  124. available: black, blue, green, cyan, red, magenta, yellow, and white.
  125.  
  126. The [monocolors] section defines monochrome mode display attributes.  The
  127. content of this section is identical to the content of the [colors] section.
  128. Due to my lack of interest in monochrome display adapters, I did not bother
  129. to define monochrome color strings.  Use blue for underlined text, or use
  130. white for normal text.  Bright and blinking are still valid attributes.
  131.  
  132. Case is not significant anywhere except the text to be printed.
  133.  
  134. -------------------------------------------------------------------------------
  135.  
  136. NCAL is freeware.
  137.  
  138.